The X-Philes (2nd Revision)/The X-Philes Number 1 (1995).iso/xphiles/psion/syscalls.1

Text File | 1995-03-31 | 36KB | 1,050 lines

PSIONICS FILE - SYSCALLS.1
==========================
System calls (part 1)
Last modified 1994-09-06
========================

The Psion System 3 operating system offers a large number of system calls.

A system call is identified by either a "function number" or by a "function
number and a "subfunction number". These are abbreviated to "Fn" and "Sub"
in the descriptions of system calls.

Each call can take up to 5 word parameters, called BX, CX, DX, SI, and DI.
In addition, there may be up to two byte parameters (AH and AL) or an
additional word parameter (AX). The values returned from the call have the
same structure; in addition, there is an error flag and three result flags
(the latter are only used by a few system calls). Note that AX is equivalent
to (AH * 256 + AL); the description will use whichever is most convenient.

There are two OPL keywords for making system calls: CALL and OS. They access
the same system calls, and differ only in the way in which the parameters are
passed and the results returned.

The CALL keyword takes from 1 to 6 arguments. If an argument is omitted, the
corresponding parameter is set to an undefined value. The first argument
should be one of:
    Fn
    Fn + 256 * Sub
    Fn + 256 * AH
according to the specific system call. The remaining arguments provide the
word parameters:
    argument 2: BX
    argument 3: CX
    argument 4: DX
    argument 5: SI
    argument 6: DI
The keyword returns a value, which is one of the results:
    AX
    AH * 256 + AL
(which are equivalent). The flags and the other 5 results are not available.

OS takes two or three arguments; if there is no third, it is taken to be
identical to the second. The first argument is Fn, while the second and third
are each the address of a 12 byte buffer, holding the parameters and results
respectively:
  Offset  0 (word): one of:
    Sub * 256 + AL    (parameters only)
    AX                (parameters and results)
    AH * 256 + AL     (parameters and results)
  Offset  2 (word): BX
  Offset  4 (word): CX
  Offset  6 (word): DX
  Offset  8 (word): SI
  Offset 10 (word): DI
The keyword returns a value which represents the error or result flags.
Each flag is held in a specific bit of the value; the remaining bits are
unspecified:
    Bit  0: UL flag or error flag (depending on context)
    Bit  6: EQ flag
    Bit  7: SL flag
Thus, if the call can fail, it has failed if the returned value is odd.

When a parameter or result is described as a cstr, a qstr, a buffer, or any
other construct requiring more than 2 bytes, the actual parameter or result is
the address of the construct.


The system calls are described in a standard form. The first line gives the
following information:
* the Fn value
* the Sub value if any
The second line gives the following:
* The name given to the call by the SDK.
* A note such as "v3.1" giving the first version of the operating system
  to support the call; if omitted, all versions support it.
* The word "fails" if the call can fail; if omitted, the call never fails.
  - If a call can fail, then the error flag shows whether or not it did so. If
    it failed, AL holds an error code between 128 and 255; this is normally
    treated as a negative number between -1 and -128, found by evaluating
    the expression (AX OR $FF00). AH, and any of the 5 word results that the
    call would have changed, are unspecified.
  - If a call cannot fail, the error flag may still be set; this should be
    ignored.
  - Even if a call cannot fail, bad parameters can cause a system panic.
* The word "async" if the call is always asynchronous, or the word "vsync" if
  it is sometimes asynchronous; if omitted, the call is synchronous.
  - A synchronous call is "completed" (has carried out all its actions) when
    the system call returns.
  - An asynchronous call returns immediately, even though the call might not
    have completed. A parameter of the call specifies a "status word", which
    the call initially sets to -46 (the error code meaning "not completed).
    When the relevant action has been taken or event occurs, the call
    is completed, the status word is changed to indicate the result of the
    call, and an IOSIGNAL is sent to the process. [This is exactly the same
    behaviour as the IOA keyword.]
  - If a call is "vsync", then it may be made as either a synchronous or
    asynchronous call:
    + to make a synchronous call, set AL to zero (the parameter giving the
      address of the status word will be ignored);
    + to make an asynchronous call, set AL to any other value (the address
      of the status word must be valid);
    + descriptions of such calls will omit AL from the list of parameters.
  - An asynchronous call may complete before returning (for example if the
    relevant event has already happened). In this case the process will never
    see the status word with the value -46, but an IOSIGNAL is still received.
  - Some asynchronous calls have a corresponding "cancel" call. This causes
    the original call to be completed with the status word set to some
    negative value other than -46.

This is then followed by a list of the parameters and results used by the
call; any parameter not listed is ignored. For the 5 main word results, the
result (if the call does not fail) is the same as the corresponding parameter
(including when the former is ignored) unless a different meaning is shown
following an arrow (->). For the results AH, AL, and AX, and also the result
flags, the result is unspecified if no such description is given.


For example, consider the following (non-existent) system call:
Fn $12 Sub $34
GetMagicCookie fails
    AX: -> magic cookie table entry zero
    BX: table entry number
    CX: -> magic cookie entry
    SI: addend -> CX out + SI in
Returns entries from the magic cookie table.

This system call could be used either by:
    entry0% = CALL ($3412, entry%, 0, 0, addend%)
which only returns magic cookie table entry zero, or by:
    LOCAL regs%(6)
    regs%(1)=$3400
    regs%(2)=entryno%
    regs%(5)=addend%
    failed%=1 AND OS ($12, ADDR(regs%()))
    REM regs%(2,4,6) have not changed
    IF NOT failed
        entry0%=regs%(1)
        entry%=regs%(3)
        REM regs%(5) will equal entry%+addend%
    ELSE
        REM regs%(1,3,5) are undefined
        error%=regs%(1) and $FF00
    ENDIF
which returns much more information.


System calls
------------

Note that some system calls are deliberately not described.


Fn $80 Sub $00
SegFreeMemory
    AX: -> free memory
Returns the amount of free system memory, in units of 16 bytes.


Fn $80 Sub $01
SegCreate fails
    AL: segment type: ordinary processes should use 1.
    AX: -> segment handle
    BX: (cstr) name of the segment
    CX: segment size in units of 16 bytes
Creates an additional memory segment. Each segment must be given a name, of the
form "8.3" (i.e. up to 8 characters, optionally followed by a dot and up to 3
more characters). If the name is already in use, the call will fail. Once
created, the segment may be used by the process as additional memory, either
via SegCopyFrom and SegCopyTo, or in assembler code (see the Psionics file
KERNEL).


Fn $80 Sub $02
SegDelete fails
    BX: segment handle
Deletes an additional memory segment. If any other process has opened the
segment, the call will fail.


Fn $80 Sub $03
SegOpen fails
    AX: -> segment handle
    BX: (cstr) name of the segment
Opens the additional memory segment with the given name (if no such segment
exists, the call will fail). The call will fail if the process has the segment
open already. Except where stated, all calls using additional memory segments
must be given handles from SegCreate or SegOpen calls.


Fn $80 Sub $04
SegClose fails
    BX: segment handle
Closes an additional memory segment which the process has open. If this was the
only process with the segment open, it is deleted. Open segments are closed
when a process terminates.


Fn $80 Sub $05
SegSize
    AX: -> segment size
    BX: segment handle
Returns the size of an additional memory segment in units of 16 bytes.


Fn $80 Sub $06
SegAdjustSize fails
    BX: segment handle
    CX: new size in units of 6 bytes
Changes the size of an additional memory segment. The memory will be added to
or removed from the end of the segment.


Fn $80 Sub $07
SegFind fails
    AX: -> segment handle
    BX: last segment handle
    SI: address of 14 byte buffer used by the call
    DI: (cstr) pattern to search for
Finds the additional memory segments with names matching the search pattern
(use ? and * as wild cards). The first call should be made with the last
segment handle set to 0, and subsequent calls should set it to the handle
returned by the previous call. The call fails when there are no more segments
to return. It is not necessary to keep calling SegFind until this happens.


Fn $80 Sub $08
SegCopyTo
    BX: segment handle
    CX: number of bytes to copy
    DX: high half of start address in segment
    SI: address in process of first byte to copy
    DI: low half of start address in segment
Copies data from the current process to an additional memory segment.


Fn $80 Sub $09
SegCopyFrom
    BX: segment handle
    CX: number of bytes to copy
    DX: high half of start address in segment
    SI: address in process to copy first byte to
    DI: low half of start address in segment
Copies data from an additional memory segment to the current process.


Fn $80 Sub $0A
SegLock
    BX: segment handle
Locks an additional memory segment; a locked segment will not be deleted even
if no processes have it open.


Fn $80 Sub $0B
SegUnLock
    BX: segment handle
Unlocks an additional memory segment. The number of unlock calls should equal
the number of lock calls; additional unlocks may cause the segment to be
deleted while still open.


Fn $80 Sub $0C
SegRamDiskUsed
    AX: -> size of the ram disc in units of 16 bytes
Returns the size of the ram disc; this should be treated carefully, as it
can change without warning.


Fn $80 Sub $0D
SegCloseLockedOrDevice
    BX: segment handle
Unlocks an additional memory segment where the handle may be that for a
different process. See SegUnLock for more details.


Fn $81 Sub $00
HeapAllocateCell fails
    AX: -> allocated block
    CX: number of bytes to allocate
Allocates a block of memory from the heap. The returned block may be larger
than requested. Heap memory is part of the process's normal memory segment.


Fn $81 Sub $01
HeapReAllocateCell fails
    AX: -> new address of block
    BX: block to be reallocated, or zero
    CX: new size of block in bytes
Changes the size of a heap block; the block may have to be moved to do this.
The memory will be added or deleted to the end of the block. If the call fails,
the block is unaffected. If BX is zero, then a new cell is allocated. The new
block may be larger than requested.


Fn $81 Sub $02
HeapAdjustCellSize fails
    AX: -> new address of block
    BX: block to be adjusted (must not be zero)
    CX: number of bytes to add or remove
    DX: location within block of the change
Changes the size of a heap block; the block may have to be moved to do this.
If the call fails, the block is unaffected. The memory will be added or removed
at the offset given by DX. For example, if the block was 10 bytes long, CX is
3, and DX is 6, the new block will be 13 bytes, and consist of the first 6
bytes of the old block, then 3 random bytes, then the last 4 bytes of the old
block. The new block may be larger than requested.


Fn $81 Sub $03
HeapFreeCell
    BX: block to free
Frees a previously allocated heap block.


Fn $81 Sub $04
HeapCellSize
    AX: -> cell size in bytes
    BX: address of block
Returns the actual size of a heap block (which may be larger than requested
when the block was created or last resized).


Fn $81 Sub $05
HeapSetGranularity
    BX: new granularity in units of 16 bytes
When the application data space is not large enough to satisfy a heap request,
it is grown by the granularity. The default is 2kb (128 units), and the
maximum is 16k (1024 units).


Fn $81 Sub $06
HeapFreeMemory
    AX: -> maximum possible free space on heap
    BX: -> address of start of heap
Returns the amount of heap space which can be allocated (by using freed blocks
or by growing the data space, or both), plus the address of the base of the
heap.


Fn $82 Sub $00
SemCreate fails
    AX: -> semaphore handle
    BX: initial value of semaphore
Creates a new semaphore for process interlocking. Each semaphore has a list of
processes associated with it (this list is initially empty) and a value, which
must initially be zero or positive.


Fn $82 Sub $01
SemDelete
    BX: semaphore handle
Deletes a semaphore. Any processes on the semaphore's list will be restarted.
When a process terminates, any semaphore it created will be deleted.


Fn $82 Sub $02
SemWait
    BX: semaphore handle
If the value of the semaphore is positive or zero, one is subtracted from it.
If the value is now or initially -1, the current process is then blocked and
added to the end of the list for that semaphore.


Fn $82 Sub $03
SemSignalOnce
    BX: semaphore handle
If the list for the semaphore is not empty, the first process on the list is
removed and restarted. If the list is empty (either initially or after the
only process is removed), one is added to the value of the semaphore. If the
restarted process has a higher priority than the current one, a reschedule
will take place and the other process will start running (see the description
of priorities in the Psionics file PROCESS).


Fn $82 Sub $04
SemSignalMany
    BX: semaphore handle
    CX: number of calls to make (must be positive)
This is equivalent to making several calls to SemSignalOnce.


Fn $82 Sub $05
SemSignalOnceNoReSched
    BX: semaphore handle
This is identical to SemSignalOnce except that a reschedule never takes place
because of the call (though one may take place due to the current process using
up its time slot).


Fn $83 Sub $00
MessInit fails
    BX: number of message slots + 256 * maximum data length
Initialize the message system so that the current process can receive
inter-process messages. The call reserves the indicated number of message
slots, with each slot having room for the indicated amount of data. The slots
are allocated on the heap.


Fn $83 Sub $01
MessReceiveAsynchronous async
    BX: address of message slot pointer
    DI: address of the status word
When a message arrives, the message slot pointer is set to the address of the
message, the status word is set to zero, and the call completes. The message
has the format:
  Offset  0 to   3: used by the message system
  Offset  4 (word): message type
  Offset  6 (word): process sending the message
  Offset  8 onward: data in message


Fn $83 Sub $02
MessReceiveWithWait
    BX: address of message slot pointer
When a message arrives (this may have happened before the call; otherwise the
call waits until a message arrives), the message slot pointer is set to the
address of the message. The message format is as for MessReceiveAsynchronous.


Fn $83 Sub $03
MessReceiveCancel
Cancel any pending MessReceiveAsynchronous.


Fn $83 Sub $04
MessSend fails
    BX: process to receive the message
    CX: message type
    SI: address of first byte of message data
Send a message to a process. The call will block until there is a free message
slot in the receiving process. The receiving process determines the amount of
data sent. The reply is ignored.


Fn $83 Sub $05
MessSendReceiveAsynchronous fails async
    BX: process to receive the message
    CX: message type
    SI: address of first byte of message data
    DI: address of the status word
Send a message to a process; when the recipient replies, the status word is
set to the reply and the process is sent an IOSIGNAL. The call will block until
there is a free message slot in the receiving process.


Fn $83 Sub $06
MessSendReceiveWithWait fails
    AX: -> reply
    BX: process to receive the message
    CX: message type
    SI: address of first byte of message data
Send a message to a process, and blocks until the recipient replies.


Fn $83 Sub $07
MessFree
    BX: address of received message
    CX: reply
The reply is sent to the recipient of the message, and the message slot is
freed and can be used for another incoming message.


Fn $83 Sub $08
MessSignal fails
    BX: process to watch
    CX: message type
Requests that, when the specified process terminates, the kernel sends a
message of the indicated type to the current process. The data in the message
has the format:
  Offset  0 (word): process id of terminating process
  Offset  2 (byte): reason code (see ProcKill) or panic code
  Offset  3 (byte):
    0 = process terminated or was killed
    1 = process caused a panic
    2 = a subtask of the process caused a panic in the process
If the message slots do not have room for 4 bytes of data, not all this
information is available.


Fn $83 Sub $09
MessSignalCancel fails
Fn $83 Sub $0A
MessSignalCancelX fails
    BX: process to watch
    CX: message type (MessSignalCancelX only)
Cancels a call to MessSignal for the indicated process. MessSignalCancel
ignores the message type and should not be used if more than one MessSignal
call has been made for the process.


Fn $84 is used to control dynamic libraries and is not described here.


Fn $85 Sub $00
IoOpen fails
    AX: -> handle of opened device
    BX: (cstr) name of device driver
    CX: mode
    DX: handle of device being attached to
Opens a channel to a device driver. If the driver is a base driver, then
DX is ignored (and this call is equivalent to the IOOPEN keyword). If it is
a stacked driver (see the Psionics file DEVICES), then the handle to be
stacked on must be specified. The meaning of the mode is determined by the
device. A driver can support several channels at once, and each has its own
handle. The driver must be a logical device driver.


Fn $85 Sub $01 and $02 involve physical device drivers and should only be
called from within logical device drivers.


Fn $85 Sub $03 to $05 should only be used by the operating system.


Fn $85 Sub $06
DevLoadLDD fails
Fn $85 Sub $07
DevLoadPDD fails
    BX: (cstr) name of file holding the driver
Loads a device driver into the system. A driver cannot be opened until it is
loaded. The correct call for the driver type must be used.


Fn $85 Sub $08
DevDelete fails
    BX: (cstr) name of the device driver
    DX: $DD01 for logical device drivers, or $DD21 for physical device drivers
Unloads a device driver from the system. Open drivers and those in the ROM
cannot be unloaded.


Fn $85 Sub $09
DevQueryUnits fails
    AX: -> number of channels supported
    BX: (cstr) name of the device driver
Returns the number of simultaneous open channels supported by a driver (which
must be a logical one); $FFFF indicates no limit.


Fn $85 Sub $0A
DevFind fails
    AX: -> find code
    BX: last find code
    DX: $DD01 for logical device drivers, or $DD21 for physical device drivers
    SI: address of 14 byte buffer
    DI: (cstr) pattern to search for
Finds all devices with names matching the search pattern (use ? and * as wild
cards). The first call should be made with the last find code set to 0, and
subsequent calls should set it to the code returned by the previous call. The
call fails when there are no more drivers to return. It is not necessary to
keep calling DevFind until this happens.


Fn $85 Sub $0B should only be used by the operating system.


Fn $85 Sub $0C is used for special operations on device drivers.


Fn $86 Sub $00
IoAsynchronous fails async
Fn $86 Sub $01
IoAsynchronousNoError async
Fn $86 Sub $02
IoWithWait fails
    AL: service number
    AX: -> result from driver
    BX: handle of driver
    CX: address of first argument
    DX: address of second argument
    DI: address of the status word (ignored by IoWithWait)
These calls are equivalent to the IOA, IOC, and IOW keywords respectively
[For those without documentation of IOC, this is the same as IOA, except that
errors are handled by setting the status word and calling IOSIGNAL, so that
IOC always succeeds, unlike IOA.]


Fn $86 Sub $03 and $04 should only be used by device drivers.


Fn $86 Sub $05
IoWaitForSignal
This call is equivalent to the IOWAIT keyword.


Fn $86 Sub $06
IoWaitForStatus
    DI: address of the status word
This call is equivalent to the IOWAIT keyword.


Fn $86 Sub $07
IoYield
    DI: address of the status word
This call is equivalent to the IOYIELD keyword.


Fn $86 Sub $08
IoSignal
Sends an IOSIGNAL to the current process. This call is equivalent to the
IOSIGNAL keyword.


Fn $86 Sub $09
IoSignalByPid fails
Fn $86 Sub $0A
IoSignalByPidNoReSched fails
    BX: process ID
Sends an IOSIGNAL to a process. With the latter call a reschedule never takes
place because of the call (though one may take place due to the current
process using up its time slot).


Fn $86 Sub $0B to $0F should only be used by device drivers.


Fn $86 Sub $10
IoClose fails
    AX: -> result from driver
    BX: handle
This call is equivalent to the IOCLOSE keyword.


Fn $86 Sub $11
IoRead fails
Fn $86 Sub $12
IoWrite fails
    AX: -> amount actually read or result from driver
    BX: handle
    CX: address of buffer
    DX: number of bytes read or written
These calls are equivalent to the IOREAD and IOWRITE keywords.


Fn $86 Sub $13
IoSeek fails
    AX: -> result from driver
    BX: handle
    CX: mode
    DX: address of long holding seek position
This call is equivalent to the IOSEEK keyword.


Fn $86 Sub $14 should only be used by the window manager.


Fn $86 Sub $15 to $17 should only by used from assembler.


Fn $86 Sub $18
IoShiftStates
    AL: modifiers
This call makes available the state of the various modifier keys:
  Bit 1: shift
  Bit 2: control
  Bit 3: psion


Fn $86 Sub $19
IoWaitForSignalNoHandler
This call should be used instead of IOSEEK by tasks (subsidiary processes of
a process).


Fn $86 Sub $1A
IoSignalKillAsynchronous fails async
    BX: process to watch
    DI: address of the status word
This call completes, and the status word is set to 0,  when the specified
process terminates.


Fn $86 Sub $1B
IoSignalKillCancel fails
    BX: process to watch
Cancel any pending IoSignalKillAsynchronous.


Fn $86 Sub $1C and $1D should only be used by the window manager.


Fn $86 Sub $1E
IoPlaySoundW v3
    AL: -> failure code
    BX: (cstr) sound file name
    CX: duration to play (in 1/32 second)
    DX: volume: 0 (loudest) to 5 (softest)
Plays a sound file. A duration of 0 means the file header specifies the
duration; otherwise, the sound is clipped or padded with space as needed.
The name may be either an ordinary filename, or a string of the form "*ABCD",
meaning the first found of the files:
    ROM::ABCD.WVE
    LOC::M:\WVE\ABCD.WVE
    LOC::A:\WVE\ABCD.WVE
    LOC::B:\WVE\ABCD.WVE
Note that this call does not fail in the usual way, but just returns a failure
code.


Fn $86 Sub $1F
IoPlaySoundA v3 async
    BX: (cstr) sound file name
    CX: duration to play (in 1/32 second)
    DX: volume: 0 (loudest) to 5 (softest)
    DI: address of the status word
Plays a sound file asynchronously; the call completes when the sound has
finished. The other arguments are as for IoPlaySoundW.


Fn $86 Sub $20
IoPlaySoundCancel v3
Cancel any pending IoPlaySoundA.


Fn $86 Sub $21
IoRecordSoundW v3
    AL: -> failure code
    BX: (cstr) sound file name
    CX: number of samples to record, in units of 2048 samples
Records a sound file. Note that 2048 samples are slightly more than a quarter
of a second. The file will be created before recording, and must not be on
a flash device. Note that this call does not fail in the usual way, but just
returns a failure code.


Fn $86 Sub $22
IoRecordSoundA v3 async
    BX: (cstr) sound file name
    CX: number of samples to record, in units of 2048 samples
    DI: address of the status word
Records a sound file asynchronously; the call completes when the recording has
finished. The other arguments are as for IoRecordSoundW.


Fn $86 Sub $23
IoRecordSoundCancel v3
Cancel any pending IoRecordSoundA.


Fn $87 Sub $00 is carried out automatically for OPL programs.


Fn $87 Sub $01
FilExecute fails vsync
    BX: (cstr) program name
    CX: (qstr) program information
    DX: address of the status word
    DI: address of word to be filled with process ID of new process
Starts a new process and places it in "suspended" state. The program
information is a qstr which normally consists of the following catenated
together (note that all these elements except the first are cstrs):
(1) the character 'C' (create new file) or 'O' (open existing file);
(2) (cstr) the application name, with the first character uppercased and the
    rest lowercased;
(3) (cstr) one of:
    (a) the normal extension for filenames, including the leading dot;
    (b) the normal extension with dot, followed by a space and aliasing
        information;
    (c) an empty string
(4) (cstr) the data file path passed as the initial argument;
(5) (cstr) the application path (may be omitted if not required).

A binary application may be used to operate on a standard file type. Examples
include:
    Program                  Application  Extension
                             [item 2]     [item 3]
    "ROM::DATA.APP"          "Data"       ".DBF"
    "ROM::WORD.APP"          "Word"       ".WRD"
    "ROM::WORD.APP"          "Program"    ".OPL"
    "LOC::C:\APP\COMMS.APP"  "Comms"      ".SCO"

In each of these cases there is no aliasing information or application path.
An example program information qstr is "OData~.DBF~LOC::M:\DBF\MYDATA.DBF~"
(tilde indicates a zero byte).

@This section needs rewriting@
The word processor may also be used as a program editor, by making item 2
its name ("Program") and item 3 an extension (usually ".OPL") followed by the
necessary aliasing information: "OROPO", where the first O is the last letter
of the name of the translator "ROM::SYS$PRGO" (and can be changed if other
translators are available), the R indicates that the translator can execute
resulting code [I don't know what value to use if it can't], and OPO is the
extension of translated files. An example program information qstr is
"Program~.OPL OROPO~LOC::M:\OPL\MYPROG.OPL~"

Finally, a translator may be used to execute a translated file: in the case
of the translator "ROM::SYS$PRGO", it can execute either OPO or OPA files.
The application name is given in the APP ... ENDA clause for OPA files, and
is "RunOpl" for OPO files; there is no extension or aliasing information.
For OPA files, the data file is passed to the application, and the application
path shows which application is actually run. For OPO files, the data file
should name the OPO file itself, and there is no application path. Examples
are "RunOpl~~M:\OPO\MYPROG.OPO~" and "MyApp~~M:\DAT\MYDATA~M:\APP\MYAPP.OPA~".


Fn $87 Sub $02
FilParse fails vsync
    BX: (cstr) file name to be parsed
    CX: (cstr) file specification to be used
    DX: address of the status word
    SI: address of a 6 byte buffer to be filled in
    DI: address of 128 byte buffer to be filled with the parsed filename
This call is equivalent to the PARSE$ keyword. The buffer is filled as follows:
  Offset  0 (byte): length of node name
  Offset  1 (byte): length of device name
  Offset  2 (byte): length of path name
  Offset  3 (byte): length of base name
  Offset  4 (byte): length of extension
  Offset  5 (byte): flags
    Bit 0: the base name or extension contains a wildcard ("*" or "?")
    Bit 1: the base name contains a wildcard
    Bit 2: the extension contains a wildcard


Fn $87 Sub $03
FilPathGet fails vsync
    BX: 128 byte buffer
    DX: address of the status word
The buffer is filled with the current filing system default path (a cstr).


Fn $87 Sub $04
FilPathSet fails vsync
    BX: (cstr) new path
    DX: address of the status word
Sets the default path (equivalent to the SETPATH keyword).


Fn $87 Sub $05
FilPathTest fails vsync
    BX: (cstr) pathname to be tested
    DX: address of the status word
Equivalent to the EXIST keyword; the call succeeds if the file with that
pathname exists.


Fn $87 Sub $06
FilDelete fails vsync
    BX: (cstr) pathname to be deleted
    DX: address of the status word
Equivalent to the DELETE keyword; non-empty directories cannot be deleted.


Fn $87 Sub $07
FilRename fails vsync
    BX: (cstr) old pathname
    CX: (cstr) new pathname
    DX: address of the status word
Equivalent to the RENAME keyword.


Fn $87 Sub $08
FilStatusGet fails async
    BX: (cstr) filename
    CX: 16 byte buffer
    DX: address of the status word
    SI: 0
    DI: 0
The buffer is filled in with information about the file:
  Offset  0 (word): buffer format version: always 2
  Offset  2 (word): attributes
  Offset  4 (long): file size in bytes
  Offset  8 (long): time last modified

The attribute bits have the following meanings (question marks indicate that
the bit name was specified but the meaning is unknown; equals signs mean that
the bit can be set by FilStatusSet):
  = Bit  0: file is not ReadOnly
  = Bit  1: file is Hidden
  = Bit  2: file is a System file
    Bit  3: file is a Volume name
    Bit  4: file is a Directory
  = Bit  5: file is Modified
  ? Bit  8: file is a readable file
  ? Bit  9: file is an executable file
  ? Bit 10: file is a byte stream file
    Bit 11: file is a text file
The LOC:: node (see Psionics file FILEIO) does not distinguish text and binary
files, and always leaves bit 11 clear. Other nodes may distinguish the types of
files and set the bit where appropriate.


Fn $87 Sub $09
FilStatusSet fails vsync
    BX: (cstr) filename
    CX: mask of attributes to be changed (only specify settable bits)
    DX: address of the status word
    SI: 0
    DI: new values for attributes to be altered
The attributes indicated in the mask of the specified file are altered to
the new values; all other attributes are left unchanged.


Fn $87 Sub $0A AL sync
FilStatusDevice fails vsync
    BX: (cstr) device name (such as "A:" or "LOC::A:")
    CX: 64 byte buffer
    DX: address of the status word
The buffer is filled in with information about the device:
  Offset  0 (word): buffer format version
  Offset  2 (byte): device type
    0 = unknown
    1 = floppy
    2 = hard disc
    3 = flash
    4 = ram
    5 = rom
    6 = write-protected
  Offset  3 (byte): device properties:
    Bit 3: formattable device
    Bit 4: dual density device
    Bit 5: internal device
    Bit 6: dynamically sizeable device
    Bit 7: compressible (worth compressing database files)
  Offset  4 (word): non-zero if the device contains removable media
  Offset  6 (long): total space on the device in bytes
  Offset 10 (long): free space on the device in bytes
  Offset 14 (cstr): volume name
  Offset 46 (word): device battery status
    0  = low battery
    1  = battery OK
    -4 = status not available for this device type
    This field is not valid if the format version (offset 0) is less than 3.


Fn $87 Sub $0B
FilStatusSystem fails vsync
    BX: (cstr) node name (such as "LOC::" or "REM::")
    CX: 32 byte buffer
    DX: address of the status word
The buffer is filled in with information about the node:
  Offset  0 (word): buffer format version (currently 2)
  Offset  2 (word): 0 = flat, 1 = hierarchical
  Offset  4 (word): non-zero if devices are formattable, and zero otherwise


Fn $87 Sub $0C
FilMakeDirectory fails vsync
    BX: (cstr) pathname
    DX: address of the status word
This is equivalent to the MKDIR keyword.


Fn $87 Sub $0D AL sync
FilOpenUnique fails vsync
    BX: (cstr) pathname
    CX: open mode (format and access parts only)
    DX: address of the status word
Open a file with a unique name. This is equivalent to the IOOPEN keyword with
a mode of 4. The pathname is used to determine the directory to create
the file in, and will be modified to give the actual name (thus the pathname
should have room for 128 characters).


Fn $87 Sub $0E
FilSystemAttach fails vsync
    BX: (cstr) name of a file system PDD
    DX: address of the status word
The specified physical device driver will be attached to the filing system,
possible adding new nodes.


Fn $87 Sub $0F
FilSystemDetach fails vsync
    BX: (cstr) name of a filing system
    DX: address of the status word
Detaches a filing system. Built-in filing systems cannot be detached.


Fn $87 Sub $10
FilPathGetById fails vsync
    BX: process to examine
    CX: 128 byte buffer
    DX: address of the status word
The buffer is set to the current path of the specified process (a cstr).


Fn $87 Sub $11
FilChangeDirectory fails vsync
    BX: (cstr) pathname
    CX: 128 byte buffer
    DX: address of the status word
    DI: 0 = get root directory, 1 = get parent directory, 2 = get subdirectory
    SI: (cstr) name of subdirectory
The path name is modified in the requested way. This call should be used
instead of manipulating the directory part of a name directly, as it works on
all nodes, irrespective of the format that the node uses for path names.


Fn $87 Sub $12 has no effect on OPL processes.


Fn $87 Sub $13
FilSetFileDate fails vsync
    BX: (cstr) pathname
    CX: low word of new time
    DX: address of the status word
    DI: high word of new time
Sets the modification time of the specified file.


Fn $87 Sub $14
FilLocChanged fails vsync
    AX: -> channel change flags
    BX: channel to check
    DX: address of the status word
Specifies whether any directory in the LOC:: node has changed (i.e. a file
or directory has been created, destroyed, or renamed, but not changes to file
contents) since the last use of this system call with this channel. BX should
have exactly one bit set, corresponding to the channel to use; bits 8 to 15
are reserved by Psion. The corresponding bit in AX will be set if the node
has changed, and will be clear otherwise; the other 15 bits are unspecified.
This call can be used to determine whether to update a directory display.


Fn $87 Sub $15
FilLocDevice v3 fails vsync
    BX: local device indicator (%A to %H, or %I or %M)
    CX: address of word set to the media type
    DX: address of the status word
Provides the media type of a device on the LOC:: node (I and M both refer to
the internal ramdisc). The device type consists of:
  Bits 0 to 3:
    0 = unknown
    1 = floppy
    2 = hard disc
    3 = flash
    4 = ram
    5 = rom
    6 = write-protected
  Bits 7 to 8:
    0 = device battery measurement not supported
    1 = device battery measurement not supported
    2 = device battery voltage low
    3 = device battery voltage good


Fn $87 Sub $16
FilLocReadPDD v3 fails vsync
    BX: local device indicator (%A to %H, or %I or %M)
    CX: (long) location on the device
    DX: address of the status word
    SI: number of bytes to read
    DI: address in process to copy first byte to
Copies data from a device on the LOC:: node to the current process. This
call is very efficient, and accesses the raw device.



Further system calls are described in Psionics file SYSCALLS.2.